Skip to main content

Bank Statement Analysis

Overview

The USA Bank Statement Analysis flow extracts and analyzes information from bank statements, including transaction data, balances, and patterns. It processes the statements to detect potential fraud indicators and provides categorized transaction data along with summary fields.

InputOutput
URL of bank statement documentExtracted transaction data, estimated revenues, information about alternate lenders, account and monthly summaries, balance information, fraud indicators, and summary fields

End-to-End Async Flow

Follow these steps to complete bank statement analysis:

Step 1. Submit your bank statement parsing request to v1/parseBankStatement and receive a success response, depicting the acceptance of the bank statements
Step 2. Create and set up a webhook endpoint to receive a notification when processing completes
Step 3. Upon webhook notification, call the results API (/getBankStatementParsingResults) to fetch the full parsing output

These steps are detailed below.

Step 1: Parse Bank Statement API

The Parse Bank Statement API submits bank statements for processing.

API URL

https://usa-engine.thomas.hyperverge.co/v1/parseBankStatement

API Endpoint

parseBankStatement

Overview

The Parse Bank Statement API is RESTful and uses standard HTTP verbs and status codes. Requests are in JSON format and responses are in JSON format. This API is now asynchronous and delivers results via a webhook notification followed by a results retrieval API.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the Parse Bank Statement API.

API Request Details

Method - POST

Headers

HeaderMandatory / OptionalDescriptionInput Format
content-typeMandatoryThis parameter defines the media type for the request payloadapplication/json
appIdMandatoryThe application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tabThis should be a unique value
appKeyMandatoryThe application key shared by HyperVerge. You can find the details in the dashboard's credentials tabThis should be a unique value
transactionIdMandatoryA unique identifier for tracking a user journeyThis should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the parameters required for the Parse Bank Statement API's request body:

ParameterMandatory / OptionalTypeDescriptionInput FormatDefault Value
bankStatementFilesMandatoryarrayAn array of objects, each containing the URL and ID of a bank statement PDF to be analyzedNot ApplicableNot Applicable
bankStatementFiles[].statementUrlMandatorystringThe URL of the bank statement PDFNot ApplicableNot Applicable
bankStatementFiles[].statementIdMandatorystringA unique identifier for the bank statement PDFNot ApplicableNot Applicable
bankStatementFiles[].passwordOptionalstringThe password to decrypt the bank statement PDF if the provided file URL points to an encrypted PDFNot ApplicableNot Applicable
merchantIdOptionalstringThe unique identifier for the merchantNot ApplicableNot Applicable
contractIdMandatorystringThe unique identifier for the contractNot ApplicableNot Applicable
merchantLegalNameMandatorystringThe legal name of the merchantNot ApplicableNot Applicable
merchantDBAMandatorystringThe 'Doing Business As' (DBA) name of the merchantNot ApplicableNot Applicable
dateOfApplicationOptionalstringThe date when the application for cash advance was receivedYYYY-MM-DDNot Applicable
checkAddressOptionalstringParameter to enable address validation. Set to "yes" to validate the provided address, or "no" to skip validationyes / nono
ownersOptionalarrayAn array of owner objects, each containing details about a business ownerNot ApplicableNot Applicable
owners[].firstNameOptionalstringThe first name of the ownerNot ApplicableNot Applicable
owners[].lastNameOptionalstringThe last name of the ownerNot ApplicableNot Applicable
owners[].middleNameOptionalstringThe middle name of the ownerNot ApplicableNot Applicable
owners[].fullNameOptionalstringThe full name of the ownerNot ApplicableNot Applicable
businessAddressOptionalobjectThe correspondance address of the businessNot ApplicableNot Applicable
minRequiredMonthsOptionalintegerMinimum number of months (1-12) required for processing. When set to a value N, enables month-based validation to ensure bank statements cover at least the previous N consecutive months. If omitted, no month-based validation is performed. Refer to the Minimum Required Months section below for detailed validation logicAn integer value ranging from 1 to 12Not Applicable
Minimum Required Months

The minRequiredMonths parameter controls month-based validation for bank statements. When set to a value N (1-12), the API performs two types of validation:

  • Minimum Coverage Validation: Verifies that the provided bank statements span at least N months of transaction history. If the statements cover fewer than N months, the API returns the error: "Bank Statement period less than N months".
  • Consecutive Months Validation: Ensures that the statements include the required N consecutive months preceding the dateOfApplication. The validation behavior varies based on which day of the month the dateOfApplication falls on:
    • If dateOfApplication is on or after the 7th: The API requires statements for the immediately preceding N months.
      Example: For a date of application of June 8th with N=3, the API expects statements covering March, April, and May.
    • If dateOfApplication is before the 7th: The validation allows for flexibility in the most recent month. Either of the following will pass validation:
      1. Statements for the immediately preceding N months, or
      2. Statements for the N months before the most recent month (effectively skipping the last month if its statement is unavailable)
      Example: For a date of application of June 6th with N=3, the API accepts statements covering either March, April, and May (the immediate last 3 months) or February, March, and April (the 3 months preceding May, with May's statement omitted).
    If statements for the required consecutive months are not provided, the API returns the error: "Last N months Bank statement missing".

If minRequiredMonths is omitted, no month-based validation is performed and all provided statements are processed regardless of their date range.

Request

The following code snippet demonstrates a standard curl request for the Parse Bank Statement API:

curl --location --request POST 'https://usa-engine.thomas.hyperverge.co/v1/parseBankStatement' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
"bankStatementFiles": [
{
"statementUrl": "<Enter_the_PDF_URL>",
"statementId": "<Enter_the_Statement_ID>",
"password": "<Enter_the_password_if_encrypted>"
},
{
"statementUrl": "<Enter_the_PDF_URL>",
"statementId": "<Enter_the_Statement_ID>",
"password": "<Enter_the_password_if_encrypted>"
}
],
"merchantId": "<Enter_the_Merchant_ID>",
"contractId": "<Enter_the_Contract_ID>",
"merchantLegalName": "<Enter_the_Merchant's_Legal_Name>",
"merchantDBA": "<Enter_the_Merchant's_Business_Name>",
"dateOfApplication": "<Enter_date_of_application_receival>",
"checkAddress" :"<Enter_yes_or_no>",
"owners": [
{
"firstName": "<Enter_owner's_first_name>",
"lastName": "<Enter_owner's_last_name>",
"middleName": "<Enter_owner's_middle_name>",
"fullName": "<Enter_owner's_full_name>"
}
],
"businessAddress": {
"fullAddress": "<Full_correspondance_address_of_the_business>",
"city": "<City_of_correspondance>",
"state": "<State_of_correspondance>",
"zip": "<ZIP>"
},
"minRequiredMonths": <Enter_minimum_required_months> // a number ranging from 1 to 12
}'

Success Response

The Parse Bank Statement API, upon successful execution returns a status code 202, which denotes that the Bank Statements have been accepted. The structure of the response is as follows:

{
"status": "success",
"statusCode": 202,
"result": {
"transactionId": "<transactionId>"
}
}

Use transactionId returned in the response above in subsequent steps. Proceed to set up the webhook to receive completion notifications.

Error Responses

The following are some error responses from the Parse Bank Statement API:

{
"status": "failure",
"statusCode": 400,
"message": "Input Validation Error: requires property <missing_parameter>"
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status CodeError MessageError DescriptionError Resolution
400Input Validation ErrorOne or more required input properties are missing from the requestVerify and provide all input properties as specified in the Inputs table
401Missing/Invalid credentialsThe request is either missing the mandatory appId and appKey combination or has invalid valuesVerify and provide valid appId and appKey in the request headers. You can find the details in the dashboard's credentials tab

Step 2: Webhook Setup

info
Webhook setup is a one-time activity. Once configured, the webhook will receive notifications for all subsequent bank statement parsing requests.

To receive notifications when parsing finishes, establish an HTTPS endpoint. The setup is as follows:

Webhook Subscription

Use the following cURL to subscribe to the webhook:


curl --location --request POST 'https://review-api-usa.idv.hyperverge.co/api/v1/config' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'Content-Type: application/json' \
--data '{
"webhookUrl": "<Webhook URL>",
"events": [
"<EVENT_1>",
"<EVENT_2>"
]
}'

Request Parameter Descriptions

Parameter Description
webhookUrlThe URL that would receive the Webhook events
eventsYou can subscribe to the following two events:
  • BANK_STATEMENT_PARSED_SUCCESSFULLY
  • BANK_STATEMENT_PARSING_FAILED

Webhook Payload

When processing completes, a webhook is delivered to your subscribed URL with the following payload structure:

{
"type": "BANK_STATEMENT_PARSED_SUCCESSFULLY",
"timestamp": "2025-10-30T16:10:00Z",
"version": "1.0",
"id": "<uuid>",
"transactionId": "<transactionId>",
"appId": "<your_appId>"
}

Payload Field Descriptions

ParameterDescription
metadataEnvelope containing identifiers for the event, including appId and transactionId
appIdYour HyperVerge application ID
transactionIdTransaction ID to use when fetching results; identical to the value returned in the Parse Bank Statement API success response
eventEvent details for the webhook notification
typeEvent type: BANK_STATEMENT_PARSED_SUCCESSFULLY or BANK_STATEMENT_PARSING_FAILED, determined by the outcome of bank statement processing
timestampISO 8601 timestamp when the event was generated
versionEvent schema version
idUnique identifier for the event

After receiving this notification, call the Retrieve Results API with the same transactionId.

Step 3: Retrieve Results API

The Retrieve Results API fetches the detailed parsing result.

API URL

https://usa-engine.thomas.hyperverge.co/v1/getBankStatementParsingResults

API Endpoint

getBankStatementParsingResults

Overview

The Retrieve Results API is RESTful and uses standard HTTP verbs and status codes. Requests are in JSON format and responses are in JSON format. This API is now asynchronous and delivers results via a webhook notification followed by a Results Retrieval API.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the Retrieve Results API.

API Request Details

Method - POST

Headers

HeaderMandatory / OptionalDescriptionInput Format
appIdMandatoryThe application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tabThis should be a unique value
appKeyMandatoryThe application key shared by HyperVerge. You can find the details in the dashboard's credentials tabThis should be a unique value
transactionIdMandatoryA unique identifier for tracking a user journeyThis should be both unique and easily associated with the user's journey in your application(s)

Request

The following code snippet demonstrates a standard curl request for the Retrieve Results API:

curl --location --request POST 'https://usa-engine.thomas.hyperverge.co/v1/getBankStatementParsingResults' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId": <Enter_the_TransactionId>' \
--data '{
}'
warning
Only the most recent data associated with a transactionId is retained; subsequent submissions with the same transactionId overwrite earlier results.

Success Response

levels of response

The Retrieve Results API's response is structured across three distinct levels of analysis:

  • Statement Level Outputs: The most granular level, represented by the statements array. This level contains detailed information about individual bank statements, including raw transaction data, statement metadata, and fraud checks specific to each statement.
  • Account Level Outputs: The intermediate level, represented by the accountSummaries array. This level aggregates data across all statements for each account, providing account-specific summaries, monthly summaries, estimated revenue, recurring transactions, and possible alternate lenders.
  • Business Checking Level Outputs: The highest level of aggregation, represented by the businessCheckingSummaries, businessCheckingRecurringTransactions , and businessCheckingPossibleAlternateLenders arrays. This level provides a comprehensive view of the business's financial health, combining data across all accounts to show overall business performance, recurring payment patterns, estimated revenue, and potential alternate lending relationships.

Each level builds upon the previous one, allowing you to analyze the data at different granularities depending on your specific needs.

The following code snippet demonstrates a success response from the Retrieve Results API:

{
"status": "success",
"statusCode": 200,
"result": {
"details": {
"contractId": "<ID>",
"merchantId": "<ID>",
"numberOfBankStatements": 2,
"numberOfMonthsProcessed": 3,
"overallProcessingTime": 3,
"activeAlternateLenders": 2,
"businessCheckingSummaries": [
{
"month": "<Month>",
"year": 2025,
"periodStartDate": "<YYYY-MM-DD>",
"periodEndDate": "<YYYY-MM-DD>",
"periodStartBalance": 1234.55,
"periodEndBalance": 1134.78,
"daysByCalMonth": "<Month>",
"averageDailyBalance": <averagedailybalance>,
"averageTransactionSize": <averagetransactionsize>,
"daysOfNegativeBalance": <daysofnegativebalance>,
"grossDeposits": <grossdeposits>,
"maxDeposit": <maxdeposit>,
"minDeposit": <mindeposit>,
"averageDeposit": <averagedeposit>,
"depositCount": <depositcount>,
"withdrawalCount": <withdrawalcount>,
"maxWithdrawal": <maxwithdrawal>,
"minWithdrawal": <minwithdrawal>,
"averageWithdrawal": <averagewithdrawal>,
"grossWithdrawals": <grosswithdrawals>,
"totalRoundNumberOfTransactions": <totalroundnumberoftransactions>,
"totalRoundNumberTransactionsSum": <totalroundnumbertransactionssum>,
"estimatedRevenue": <estimatedrevenue>,
"totalInterbankTransfers": <totalinterbanktransfers>,
"suspiciousActivity": "<suspiciousactivity>",
"authenticityScore": <authenticityscore>,
"periodBalanceMismatch": "<periodbalancemismatch>"
}
],
"businessCheckingRecurringTransactions": [
{
"firstTxnDate": "<YYYY-MM-DD>",
"latestTxnDate": "<YYYY-MM-DD>",
"totalCountOfInstallments": <totalcountofinstallments>,
"avgDaysInterval": <avgdaysinterval>,
"avgAmount": <Amount>,
"type": "<type>",
"installments": [
{
"amount": <Amount>,
"installmentsCount": <installmentscount>
}
],
"transactions": [
{
"amount": <Amount>,
"description": "<Description>",
"txnDate": "<YYYY-MM-DD>",
"txnId": "<ID>",
"isRecurringTransaction": true/false,
"isPossibleAlternateLender": true/false
}
]
}
],
"businessCheckingPossibleAlternateLenders": [
{
"lenderName": "<Name>",
"firstTxnDate": "<YYYY-MM-DD>",
"latestTxnDate": "<YYYY-MM-DD>",
"isActive": true/false,
"totalCountOfInstallments": <totalcountofinstallments>,
"avgDaysInterval": <avgdaysinterval>,
"frequency": "<frequency>",
"totalAmountPaid": <Amount>,
"avgAmount": <Amount>,
"type": "<type>",
"installments": [
{
"amount": <Amount>,
"installmentsCount": <installmentscount>
}
],
"transactions": [
{
"amount": <Amount>,
"description": "<Description>",
"txnDate": "<YYYY-MM-DD>",
"txnId": "<ID>",
"isRecurringTransaction": true/false,
"isPossibleAlternateLender": true/false
}
],
"cashAdvance": {
"amount": <Amount>,
"description": "<Description>",
"txnDate": "<YYYY-MM-DD>",
"txnId": "<ID>",
"isRevenue": true/false,
"isPossibleAlternateLender": true/false
}
}
],
"accountSummaries": [
{
"accountNumber": "<accountnumber>",
"accountId": "<ID>",
"accountCategory": "<accountcategory>",
"accountType": "<accounttype>",
"activeAlternateLenders": <activealternatelenders>,
"monthlySummaries": [
{
"month": "<Month>",
"year": <Year>,
"periodStartDate": "<YYYY-MM-DD>",
"periodEndDate": "<YYYY-MM-DD>",
"periodStartBalance": <periodstartbalance>,
"periodEndBalance": <periodendbalance>,
"daysByCalMonth": <Days>,
"averageDailyBalance": <averagedailybalance>,
"averageTransactionSize": <averagetransactionsize>,
"daysOfNegativeBalance": <daysofnegativebalance>,
"grossDeposits": <grossdeposits>,
"maxDeposit": <maxdeposit>,
"minDeposit": <mindeposit>,
"averageDeposit": <averagedeposit>,
"depositCount": <depositcount>,
"withdrawalCount": <withdrawalcount>,
"maxWithdrawal": <maxwithdrawal>,
"minWithdrawal": <minwithdrawal>,
"averageWithdrawal": <averagewithdrawal>,
"grossWithdrawals": <grosswithdrawals>,
"totalRoundNumberOfTransactions": <totalroundnumberoftransactions>,
"totalRoundNumberTransactionsSum": <totalroundnumbertransactionssum>,
"estimatedRevenue": <estimatedrevenue>,
"totalInterbankTransfers": <totalinterbanktransfers>,
"suspiciousActivity": "<suspiciousactivity>",
"authenticityScore": <authenticityscore>,
"periodBalanceMismatch": "<periodbalancemismatch>"
}
],
"transactions": {
"withdrawals": [
{
"amount": <Amount>,
"description": "<Description>",
"txnDate": "<YYYY-MM-DD>",
"txnId": "<ID>",
"isPossibleAlternateLender": true/false,
"isRecurringTransaction": true/false
}
],
"deposits": [
{
"amount": <Amount>,
"description": "<Description>",
"txnDate": "<YYYY-MM-DD>",
"txnId": "<ID>",
"isRevenue": true/false,
"isPossibleAlternateLender": true/false
}
]
},
"recurringTransactions": [
{
"firstTxnDate": "<YYYY-MM-DD>",
"latestTxnDate": "<YYYY-MM-DD>",
"totalCountOfInstallments": <totalcountofinstallments>,
"avgDaysInterval": <avgdaysinterval>,
"avgAmount": <Amount>,
"type": "<type>",
"installments": [
{
"amount": <Amount>,
"installmentsCount": <installmentscount>
}
],
"transactions": [
{
"amount": <Amount>,
"description": "<Description>",
"txnDate": "<YYYY-MM-DD>",
"txnId": "<ID>",
"isRecurringTransaction": true/false,
"isPossibleAlternateLender": true/false
}
]
}
],
"possibleAlternateLenders": [
{
"lenderName": "<Name>",
"firstTxnDate": "<YYYY-MM-DD>",
"latestTxnDate": "<YYYY-MM-DD>",
"isActive": true/false,
"totalCountOfInstallments": <totalcountofinstallments>,
"avgDaysInterval": <avgdaysinterval>,
"frequency": "<frequency>",
"totalAmountPaid": <Amount>,
"avgAmount": <Amount>,
"type": "<type>",
"installments": [
{
"amount": <Amount>,
"installmentsCount": <installmentscount>
}
],
"transactions": [
{
"amount": <Amount>,
"description": "<Description>",
"txnDate": "<YYYY-MM-DD>",
"txnId": "<ID>",
"isRecurringTransaction": true/false,
"isPossibleAlternateLender": true/false
}
],
"cashAdvance": {
"amount": <Amount>,
"description": "<Description>",
"txnDate": "<YYYY-MM-DD>",
"txnId": "<ID>",
"isRevenue": true/false,
"isPossibleAlternateLender": true/false
}
}
],
"interbankTransactions": {
"withdrawals": "<withdrawals>",
"deposits": "<deposits>"
}
}
],
"statements": [
{
"fileName": "<Name>",
"statementId": "<ID>",
"numberOfPages": "<numberofpages>",
"bankName": "<Name>",
"processingStatus": "<processingstatus>",
"pdfType": "<pdftype>",
"statementProcessingTime": "<statementprocessingtime>",
"isValidUsBankStatement": "<isvalidusbankstatement>",
"accounts": [
{
"accountNumber": "<accountnumber>",
"accountType": "<accounttype>",
"statementSummary": {
"periodStartDate": "<YYYY-MM-DD>",
"periodEndDate": "<YYYY-MM-DD>",
"periodStartBalance": <periodstartbalance>,
"periodEndBalance": <periodendbalance>,
"averageDailyBalance": <averagedailybalance>,
"averageTransactionSize": <averagetransactionsize>,
"daysOfNegativeBalance": <daysofnegativebalance>,
"grossDeposits": <grossdeposits>,
"maxDeposit": <maxdeposit>,
"minDeposit": <mindeposit>,
"averageDeposit": <averagedeposit>,
"depositCount": <depositcount>,
"withdrawalCount": <withdrawalcount>,
"maxWithdrawal": <maxwithdrawal>,
"minWithdrawal": <minwithdrawal>,
"averageWithdrawal": <averagewithdrawal>,
"grossWithdrawals": <grosswithdrawals>,
"totalRoundNumberOfTransactions": <totalroundnumberoftransactions>,
"totalRoundNumberTransactionsSum": <totalroundnumbertransactionssum>,
"suspiciousActivity": "<suspiciousactivity>",
"authenticityScore": <authenticityscore>,
"periodBalanceMismatch": "<periodbalancemismatch>"
},
"transactions": {
"withdrawals": [
{
"amount": <Amount>,
"description": "<Description>",
"txnDate": "<YYYY-MM-DD>",
"txnId": "<ID>",
"isPossibleAlternateLender": true/false,
"isRecurringTransaction": true/false
}
],
"deposits": [
{
"amount": <Amount>,
"description": "<Description>",
"txnDate": "<YYYY-MM-DD>",
"txnId": "<ID>",
"isRevenue": true/false,
"isPossibleAlternateLender": true/false,
"isRecurringTransaction": true/false
}
]
}
}
],
"fraudChecks": {
"businessNameMismatch": true/false,
"businessOwnerNameMismatch": true/false,
"businessAddressMismatch": true/false,
"periodBalanceMismatch": true/false,
"pdfCreationDateAnomaly": true/false,
"fingerprintAnomaly": true/false,
"pdfTemplateAnomaly": true/false,
"pdfSourceAnomaly": true/false,
"bankRoutingNumberAnomaly": true/false,
"metadataAnomaly": true/false,
"contentOverlapAnomaly": true/false,
"textTampering": {
"accountNumber": true/false,
"accountOwner": true/false,
"accountType": true/false,
"address": true/false,
"transactionAmount": true/false,
"transactionDate": true/false
}
}
}
]
},
"summary": {
"action": "",
"details": []
}
}
}

Success Response Details

Main Response Arrays

The following table details all response parameters. The main arrays in the response are highlighted.

  • businessCheckingSummaries: Contains monthly summaries for all the checking accounts of a business
  • businessCheckingRecurringTransactions: Contains recurring transaction patterns across all the checking accounts of a business
  • businessCheckingPossibleAlternateLenders: Contains information about potential alternate lenders for all the checking accounts of a business
  • accountSummaries: Contains detailed summaries for each account
  • statements: Contains raw statement data and fraud checks

The following table outlines the details of the success response from the Retrieve Results API:

ParameterTypeDescription
statusstringStatus of the API response
statusCodenumberHTTP status code of the response
resultobjectMain result object containing the response data
detailsobjectMain response object containing all data
contractIdstringUnique Contract ID assigned to the application which contains the input bank statements
merchantIdstringUnique Merchant ID assigned to the merchant applying for cash advance
numberOfBankStatementsnumberTotal number of PDF bank statements sent in the input
numberOfMonthsProcessednumberTotal number of months for which particular bank statement has accounted details
overallProcessingTimenumberTotal processing time across bank statements shared in seconds
activeAlternateLendersarrayArray of active alternate lenders identified with active installments
businessCheckingSummaries
businessCheckingSummariesarrayArray of business checking summary objects
businessCheckingSummaries.monthstringName of the month or which monthly summary is listed
businessCheckingSummaries.yearnumberCalendar year of month for which monthly summary is listed
businessCheckingSummaries.periodStartDatestringStart date of the period (YYYY-MM-DD format)
businessCheckingSummaries.periodEndDatestringEnd date of the period (YYYY-MM-DD format)
businessCheckingSummaries.periodStartBalancenumberCombined account balance at the start of the period
businessCheckingSummaries.periodEndBalancenumberCombined account balance at the end of the period
businessCheckingSummaries.daysByCalMonthstringNumber of days in the calendar month
businessCheckingSummaries.averageDailyBalancenumberAverage daily balance
businessCheckingSummaries.averageTransactionSizenumberAverage transaction size
businessCheckingSummaries.daysOfNegativeBalancenumberUnique days with negative balance in any of the business checking accounts
businessCheckingSummaries.grossDepositsnumberSum of total deposit transaction values in the period
businessCheckingSummaries.maxDepositnumberMaximum deposit amount
businessCheckingSummaries.minDepositnumberMinimum deposit amount
businessCheckingSummaries.averageDepositnumberAverage deposit amount
businessCheckingSummaries.depositCountnumberTotal number of deposits
businessCheckingSummaries.withdrawalCountnumberTotal number of withdrawals
businessCheckingSummaries.maxWithdrawalnumberMaximum withdrawal amount
businessCheckingSummaries.minWithdrawalnumberMinimum withdrawal amount
businessCheckingSummaries.averageWithdrawalnumberAverage withdrawal transaction value across business checking accounts in the month
businessCheckingSummaries.grossWithdrawalsnumberSum of total withdrawal transaction values in the period
businessCheckingSummaries.totalRoundnumberOfTransactionsnumberTotal number of round number transactions
businessCheckingSummaries.totalRoundnumberTransactionsSumnumberSum of all round number transactions
businessCheckingSummaries.estimatedRevenuenumberTotal value of all revenue category transactions in the month
businessCheckingSummaries.totalInterbankTransfersnumberTotal number of interbank transfers (to and from)
businessCheckingSummaries.suspiciousActivitystringIndicates if suspicious activity(fraud indictaor) was detected
businessCheckingSummaries.authenticityScorenumberScore indicating the authenticity of the data
businessCheckingSummaries.periodBalanceMismatchstringIndicates whether there is a mismatch between balance calculated based on transactions and balance recorded during the period
businessCheckingRecurringTransactions
businessCheckingRecurringTransactionsarrayArray of recurring transactions for business checking accounts
businessCheckingRecurringTransactions.firstTxnDatestringDate of first transaction (YYYY-MM-DD) in the series of recurring transactions
businessCheckingRecurringTransactions.latestTxnDatestringDate of latest transaction (YYYY-MM-DD) in the series of recurring transactions
businessCheckingRecurringTransactions.totalCountOfInstallmentsnumberTotal number of installments in the series of recurring transactions
businessCheckingRecurringTransactions.avgDaysIntervalnumberAverage number of days between two installments in the series
businessCheckingRecurringTransactions.avgAmountnumberAverage value of transaction in the series
businessCheckingRecurringTransactions.typestringType of recurring transaction (withdrawl/deposit)
businessCheckingRecurringTransactions.installmentsobjectObject containing installment data
installmentsarrayArray of installment objects
installments.amountnumberValue of amount of the installment
installments.installmentsCountnumberNumber of installments with the specific installment amount as value
businessCheckingRecurringTransactions.transactionsobjectObject containing transaction data
businessCheckingRecurringTransactions.transactions.arrayArray of transaction objects
transactions.amountnumberValue of the transaction
transactions.descriptionstringDescription of the transaction
transactions.txnDatestringTransaction date (YYYY-MM-DD)
transactions.txnIdstringUnique transaction identifier
transactions.isRecurringTransactionbooleanIndicates whether the given transaction is part of a series of recurrent transactions
transactions.isPossibleAlternateLenderbooleanIndicates whether the transaction has been identified as a transaction with an alternate lender
businessCheckingPossibleAlternateLenders
businessCheckingPossibleAlternateLendersarrayArray of possible alternate lenders for business checking accounts
businessCheckingPossibleAlternateLenders.objectIndividual possible alternate lender object
businessCheckingPossibleAlternateLenders.lenderNamestringName of the lender identified using transaction description
businessCheckingPossibleAlternateLenders.firstTxnDatestringDate of first transaction (YYYY-MM-DD) with the lender
businessCheckingPossibleAlternateLenders.latestTxnDatestringDate of latest transaction (YYYY-MM-DD) with the lender
businessCheckingPossibleAlternateLenders.isActivebooleanIndicates if the lender is active with the lender
businessCheckingPossibleAlternateLenders.totalCountOfInstallmentsnumberTotal number of installments paid to the lender
businessCheckingPossibleAlternateLenders.avgDaysIntervalnumberAverage days between transactions
businessCheckingPossibleAlternateLenders.frequencystringTransaction payout frequency
businessCheckingPossibleAlternateLenders.totalAmountPaidnumberTotal amount paid to the lender
businessCheckingPossibleAlternateLenders.avgAmountnumberAverage transaction amount
businessCheckingPossibleAlternateLenders.typestringType of transaction
businessCheckingPossibleAlternateLenders.installmentsobjectObject containing installment data
businessCheckingPossibleAlternateLenders.installments.arrayArray of installment objects
accountSummaries
accountSummariesarrayArray of account summary objects
accountSummaries.objectIndividual account summary object
accountSummaries.accountnumberstringBank Account Number
accountSummaries.accountIdstringUnique account identifier
If sub-account number is present in the statement: Last 2 digits of account number (XY) + Last 2 digits sub account number (AB) + Bank name in the format XYAB-Bank Name.
If sub-account number is not present in the statement: Last 4 digits of account number (VWXY) + Bank name in the format VWXY-Bank Name
accountSummaries.accountCategorystringCategory of the account (Business/Personal)
accountSummaries.accountTypestringType of the account (Savings/Checkings)
accountSummaries.activeAlternateLendersnumberNumber of active alternate lenders identified with active installments
accountSummaries.monthlySummariesobjectObject containing monthly summary data
accountSummaries.monthlySummaries.arrayArray of monthly summary objects
accountSummaries.monthlySummaries.monthstringName of month for which monthly summary is listed
accountSummaries.monthlySummaries.yearnumberCalendar year of month for which monthly summary is listed
accountSummaries.monthlySummaries.periodStartDatestringStart date of the period (YYYY-MM-DD)
accountSummaries.monthlySummaries.periodEndDatestringEnd date of the period (YYYY-MM-DD)
accountSummaries.monthlySummaries.periodStartBalancenumberAccount balance at the start of the period
accountSummaries.monthlySummaries.periodEndBalancenumberAccount balance at the end of the period
accountSummaries.monthlySummaries.daysByCalMonthnumberNumber of calendar days with transactions with the account in the period
accountSummaries.monthlySummaries.averageDailyBalancenumberValue of average daily balance in the in the account in the period
accountSummaries.monthlySummaries.averageTransactionSizenumberValue of average transaction size in the period
accountSummaries.monthlySummaries.daysOfNegativeBalancenumberNumber of days with negative balance in the account
accountSummaries.monthlySummaries.grossDepositsnumberSum of total deposit transaction values in the period
accountSummaries.monthlySummaries.maxDepositnumberValue of maximum deposit in the period
accountSummaries.monthlySummaries.minDepositnumberValue of minimum deposit in the period
accountSummaries.monthlySummaries.averageDepositnumberAverage deposit transaction value in the month
accountSummaries.monthlySummaries.depositCountnumberTotal number of deposits
accountSummaries.monthlySummaries.withdrawalCountnumberTotal number of withdrawals
accountSummaries.monthlySummaries.maxWithdrawalnumberMaximum withdrawal amount
accountSummaries.monthlySummaries.minWithdrawalnumberMinimum withdrawal amount
accountSummaries.monthlySummaries.averageWithdrawalnumberAverage withdrawal amount
accountSummaries.monthlySummaries.grossWithdrawalsnumberSum of total withdrawal transaction values in the month
accountSummaries.monthlySummaries.totalRoundnumberOfTransactionsnumberTotal number of transactions where the amount is a whole number
accountSummaries.monthlySummaries.totalRoundnumberTransactionsSumnumberSum of all round number transactions
accountSummaries.monthlySummaries.estimatedRevenuenumberEstimated revenue
accountSummaries.monthlySummaries.totalInterbankTransfersnumberCount of number of transactions to and from a different bank in the period
accountSummaries.monthlySummaries.suspiciousActivitystringIndicates if suspicious activity or fraud indicators were detected
accountSummaries.monthlySummaries.authenticityScorenumberScore indicating the authenticity of the data
accountSummaries.monthlySummaries.periodBalanceMismatchstringIndicates whether there is a mismatch between balance calculated based on transactions and balance recorded
accountSummaries.transactionsobjectObject containing transaction data
accountSummaries.transactions.withdrawalsobjectObject containing withdrawal transactions
accountSummaries.transactions.withdrawals.arrayArray of withdrawal transaction objects
accountSummaries.transactions.withdrawls.amountnumberWithdrawal amount
accountSummaries.transactions.withdrawls.descriptionstringWithdrawal description
accountSummaries.transactions.withdrawls.txnDatestringTransaction date (YYYY-MM-DD)
accountSummaries.transactions.withdrawls.txnIdstringUnique transaction identifier
accountSummaries.transactions.withdrawls.isPossibleAlternateLenderbooleanIndicates whether the transaction has been identified as a transaction with an alternate lender
accountSummaries.transactions.withdrawls.isRecurringTransactionbooleanIndicates whether the given transaction is part of a series of recurrent transactions
accountSummaries.transactions.depositsobjectObject containing deposit transactions
accountSummaries.transactions.deposits.arrayArray of deposit transaction objects
accountSummaries.transactions.deposits.amountnumberDeposit amount
accountSummaries.transactions.deposits.descriptionstringDeposit description
accountSummaries.transactions.deposits.txnDatestringTransaction date (YYYY-MM-DD)
accountSummaries.transactions.deposits.txnIdstringUnique transaction identifier
accountSummaries.transactions.deposits.isRevenuestringIndicates whether the transaction has been identified as revenue
accountSummaries.transactions.deposits.isPossibleAlternateLenderstringIndicates whether the transaction has been identified as a transaction with an alternate lender
accountSummaries.recurringTransactionsobjectObject containing recurring transaction data
accountSummaries.recurringTransactions.arrayArray of recurring transaction objects
accountSummaries.recurringTransactions.firstTxnDatestringDate of first transaction (YYYY-MM-DD) with the lender
accountSummaries.recurringTransactions.latestTxnDatestringDate of latest transaction (YYYY-MM-DD) with the lender
accountSummaries.recurringTransactions.totalCountOfInstallmentsnumberTotal number of installments in the series of recurring transactions
accountSummaries.recurringTransactions.avgDaysIntervalnumberAverage days between transactions
accountSummaries.recurringTransactions.avgAmountnumberAverage transaction amount
accountSummaries.recurringTransactions.typestringType of recurring transaction
accountSummaries.recurringTransactions.installmentsobjectObject containing installment data
accountSummaries.recurringTransactions.installments.arrayArray of installment objects
accountSummaries.recurringTransactions.installments..amountnumberInstallment amount
accountSummaries.recurringTransactions.installments..installmentsCountnumbernumber of installments
accountSummaries.recurringTransactions.transactionsobjectObject containing transaction data
accountSummaries.recurringTransactions.transactions.arrayArray of transaction objects
accountSummaries.recurringTransactions.transactions.amountnumberTransaction amount
accountSummaries.recurringTransactions.transactions.descriptionstringTransaction description
accountSummaries.recurringTransactions.transactions.txnDatestringTransaction date (YYYY-MM-DD)
accountSummaries.recurringTransactions.transactions.txnIdstringUnique transaction identifier
accountSummaries.recurringTransactions.transactions.isRecurringTransactionstringIndicates if this is a recurring transaction
accountSummaries.recurringTransactions.transactions.isPossibleAlternateLenderstringIndicates if this is a possible alternate lender transaction
accountSummaries.possibleAlternateLendersobjectObject containing possible alternate lender data
accountSummaries.possibleAlternateLenders.arrayArray of possible alternate lender objects
accountSummaries.possibleAlternateLenders.lenderNamestringName of the lender
accountSummaries.possibleAlternateLenders.firstTxnDatestringDate of first transaction (YYYY-MM-DD)
accountSummaries.possibleAlternateLenders.latestTxnDatestringDate of latest transaction (YYYY-MM-DD)
accountSummaries.possibleAlternateLenders.isActivestringIndicates if the lender is active
accountSummaries.possibleAlternateLenders.totalCountOfInstallmentsnumberTotal number of installments
accountSummaries.possibleAlternateLenders.avgDaysIntervalnumberAverage days between transactions
accountSummaries.possibleAlternateLenders.frequencystringTransaction frequency
accountSummaries.possibleAlternateLenders.totalAmountPaidnumberTotal amount paid to the lender
accountSummaries.possibleAlternateLenders.avgAmountnumberAverage transaction amount
accountSummaries.possibleAlternateLenders.typestringType of transaction
accountSummaries.possibleAlternateLenders.installmentsobjectObject containing installment data
accountSummaries.possibleAlternateLenders.installments.arrayArray of installment objects
accountSummaries.possibleAlternateLenders.installments..amountnumberInstallment amount
accountSummaries.possibleAlternateLenders.installments..installmentsCountnumbernumber of installments
accountSummaries.possibleAlternateLenders.transactionsobjectObject containing transaction data
accountSummaries.possibleAlternateLenders.transactions.arrayArray of transaction objects
accountSummaries.possibleAlternateLenders.transactions.amountnumberTransaction amount
accountSummaries.possibleAlternateLenders.transactions.descriptionstringTransaction description
accountSummaries.possibleAlternateLenders.transactions.txnDatestringTransaction date (YYYY-MM-DD)
accountSummaries.possibleAlternateLenders.transactions.txnIdstringUnique transaction identifier
accountSummaries.possibleAlternateLenders.transactions.isRecurringTransactionstringIndicates if this is a recurring transaction
accountSummaries.possibleAlternateLenders.transactions.isPossibleAlternateLenderstringIndicates if this is a possible alternate lender transaction
accountSummaries.possibleAlternateLenders.cashAdvanceobjectObject containing cash advance data
accountSummaries.possibleAlternateLenders.cashAdvance.amountnumberCash advance amount
accountSummaries.possibleAlternateLenders.cashAdvance.descriptionstringCash advance description
accountSummaries.possibleAlternateLenders.cashAdvance.txnDatestringCash advance date (YYYY-MM-DD)
accountSummaries.possibleAlternateLenders.cashAdvance.txnIdstringUnique transaction identifier
accountSummaries.possibleAlternateLenders.cashAdvance.isRevenuestringIndicates if this is a revenue transaction
accountSummaries.possibleAlternateLenders.cashAdvance.isPossibleAlternateLenderstringIndicates if this is a possible alternate lender transaction
accountSummaries.interbankTransactionsobjectObject containing interbank transaction data
accountSummaries.interbankTransactions.withdrawalsstringWithdrawal transactions
accountSummaries.interbankTransactions.depositsstringDeposit transactions
statements
statementsarrayArray of statement objects
statementsobjectIndividual statement object
statements.fileNamestringThe file name of the bank statement PDF
statements.statementIdnumberThe statementIdthat was passed in the request
statements.numberOfPagesnumbernumber of pages in the statement
statements.bankNamenumberName of the bank whose accounts are present in the statement
statements.processingStatusstringStatus of the statement processing request. Values: Processed, Not Processed, or failed. failed indicates the PDF was not identified as a valid US bank statement
statements.pdfTypestringType of the PDF (Native/Scanned)
statements.statementProcessingTimenumberTime taken to process and analyse the statement in seconds
statements.isValidUsBankStatementbooleanWhether the PDF was classified as a valid US bank statement. true when the statement is valid; false when the upload was not identified as a valid US bank statement
statements.accountsarrayArray of account objects
statements.accounts.objectIndividual account object
statements.accounts.accountnumberstringBank Account Number
statements.accounts.accountTypestringType of the account (Savings/Checkings)
statements.accounts.statementSummaryobjectSummary of the statement
statements.accounts.statementSummary.authenticityScorenumberScore indicating the authenticity of the data
statements.accounts.statementSummary.averageDailyBalancestringAverage daily balance
statements.accounts.statementSummary.averageDepositnumberAverage deposit amount
statements.accounts.statementSummary.averageTransactionSizenumberAverage transaction size
statements.accounts.statementSummary.averageWithdrawalnumberAverage withdrawal amount
statements.accounts.statementSummary.daysOfNegativeBalancenumbernumber of days with negative balance
statements.accounts.statementSummary.depositCountnumberTotal number of deposits
statements.accounts.statementSummary.grossDepositsnumberTotal gross deposits
statements.accounts.statementSummary.grossWithdrawalsnumberTotal gross withdrawals
statements.accounts.statementSummary.maxDepositnumberMaximum deposit amount
statements.accounts.statementSummary.maxWithdrawalnumberMaximum withdrawal amount
statements.accounts.statementSummary.minDepositnumberMinimum deposit amount
statements.accounts.statementSummary.minWithdrawalnumberMinimum withdrawal amount
statements.accounts.statementSummary.periodBalanceMismatchstringIndicates if there is a balance mismatch in the period
statements.accounts.statementSummary.periodEndBalancenumberBalance at the end of the period
statements.accounts.statementSummary.periodEndDatestringEnd date of the period (YYYY-MM-DD format)
statements.accounts.statementSummary.periodStartDatestringStart date of the period (YYYY-MM-DD format)
statements.accounts.statementSummary.suspiciousActivitystringIndicates if suspicious activity was detected
statements.accounts.statementSummary.totalRoundnumberOfTransactionsnumberTotal number of round number transactions
statements.accounts.statementSummary.totalRoundnumberTransactionsSumnumberSum of all round number transactions
statements.accounts.statementSummary.withdrawalCountnumberTotal number of withdrawals
statements.accounts.transactionsobjectObject containing transaction data
statements.accounts.transactions.depositsarrayArray of deposit transactions
statements.accounts.transactions.deposits.objectIndividual deposit transaction object
statements.accounts.transactions.deposits.amountnumberDeposit amount
statements.accounts.transactions.deposits.descriptionstringDeposit description
statements.accounts.transactions.deposits.txnDatestringTransaction date (YYYY-MM-DD)
statements.accounts.transactions.deposits.txnIdstringUnique transaction identifier
statements.accounts.transactions.deposits.isRevenuebooleanIndicates whether the transaction has been identified as revenue
statements.accounts.transactions.deposits.isPossibleAlternateLenderbooleanIndicates whether the transaction has been identified as a transaction with an alternate lender
statements.accounts.transactions.deposits.isRecurringTransactionbooleanIndicates whether the given transaction is part of a series of recurring transactions
statements.accounts.transactions.withdrawalsarrayArray of withdrawal transactions
statements.accounts.transactions.withdrawals.objectIndividual withdrawal transaction object
statements.accounts.transactions.withdrawals.amountnumberWithdrawal amount
statements.accounts.transactions.withdrawals.descriptionstringWithdrawal description
statements.accounts.transactions.withdrawals.txnDatestringTransaction date (YYYY-MM-DD)
statements.accounts.transactions.withdrawals.txnIdstringUnique transaction identifier
statements.accounts.transactions.withdrawals.isRecurringTransactionbooleanIndicates if this is a recurring transaction
statements.accounts.transactions.withdrawals.isPossibleAlternateLenderbooleanIndicates if this is a possible alternate lender transaction
statements.bankNamestringName of the bank
statements.statementIdstringThe unique statement ID that was passed in the reuqest
statements.fraudChecksobjectObject containing fraud check data
statements.fraudChecks.businessNameMismatchbooleanIndicates if the business name on the bank statement does not match the name provided in the input
statements.fraudChecks.businessOwnerNameMismatchbooleanIndicates if the business owner's name on the bank statement differs from the name in input
statements.fraudChecks.businessAddressMismatchbooleanIndicates if the business address on the bank statement differs from the address in input
statements.fraudChecks.contentOverlapAnomalybooleanDetects instances where images, text or numerical values overlap, which could indicate forgery or manipulation
statements.fraudChecks.fingerprintAnomalybooleanVerifies if the document has a unique and valid fingerprint, ensuring authenticity
statements.fraudChecks.metadataAnomalybooleanAnalyzes the metadata of the document for anomalies such as inconsistent creation or modification timestamps
statements.fraudChecks.pdfCreationDateAnomalybooleanIndicates if there is a PDF creation date anomaly
statements.fraudChecks.pdfSourceAnomalybooleanIdentifies if the PDF was processed using untrusted or suspicious tools such as "ilovepdf" or similar online document editors
statements.fraudChecks.bankRoutingnumberAnomalybooleanIndicates if there is a bank routing number anomaly
statements.fraudChecks.pdfTemplateAnomalybooleanDetects if the document matches a known fraudulent or manipulated bank statement template
statements.fraudChecks.periodBalanceMismatchbooleanIndicates if there is a mismatch between balance calculated based on transactions and balance recorded
statements.fraudChecks.textTamperingobjectObject containing list of specific fields in the statement with suspected tampering flag based on font/template/spacing inconsistencies
statements.fraudChecks.textTampering.accountnumberbooleanIndicates if there is text tampering in the Bank Account Number
statements.fraudChecks.textTampering.accountOwnerbooleanIndicates if there is text tampering in the account owner details
statements.fraudChecks.textTampering.accountTypebooleanIndicates if there is text tampering in the account type
statements.fraudChecks.textTampering.addressbooleanIndicates if there is text tampering in the address
statements.fraudChecks.textTampering.transactionAmountbooleanIndicates if there is text tampering in the transaction amount
statements.fraudChecks.textTampering.transactionDatebooleanIndicates if there is text tampering in the transaction date

Errors Responses

The following errors may be returned by the Retrieve Results API:

{
"status": "failure",
"statusCode": 400,
"message": "No files downloadable"
}
{
"status": "failure",
"statusCode": 422,
"message": "No valid US Bank Statements found"
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status CodeError MessageError DescriptionError Resolution
400No files downloadableThe provided bank statement URLs could not be downloadedVerify that the URLs are accessible and publicly available, or retry the request after some time
400Files could not be openedThe bank statement files could not be opened or processedEnsure the files are valid PDFs and not corrupted. Retry the request with valid files
400Invalid passwordThe provided password for encrypted PDF is incorrectProvide the correct password for the encrypted PDF or remove the password parameter if the PDF is not encrypted
400TransactionId not foundThe provided transactionId does not exist or has not been processed yetVerify the transactionId and ensure the Parse Bank Statement API has been called successfully. Wait for processing to complete if the request was recently submitted
422No valid US Bank Statements foundNone of the uploaded PDFs were identified as valid US bank statementsEnsure at least one of the provided files is a valid US bank statement PDF. Verify the file format and content
422Bank Statement period less than N monthsThis error occurs when minRequiredMonths is set to N and the provided bank statements cover fewer than N months of transaction history. The transaction history spans less than N months.Provide bank statements that cover at least N months of transaction history, where N is the value specified in minRequiredMonths
422Last N months Bank statement missingThis error occurs when minRequiredMonths is set to N and the previous N consecutive months relative to dateOfApplication are not covered. Refer to the Minimum Required Months section for detailed understanding of this errorInclude statements for the required N consecutive months based on dateOfApplication. If the date of application is on or after the 7th of the month, include the immediate last N months. If before the 7th, you can include either the immediate last N months or the N months prior to the last month (if the last month's statement is unavailable)
500Internal Server ErrorAn internal server error occurred. Please contact the HyperVerge team for resolutionRetry the request after some time or contact the HyperVerge team if the issue persists
Was this helpful?
Ask AIBeta
Hi! How can I help?
Ask me anything about HyperVerge products, APIs, and SDKs.
Try asking: